Version 1.1: Adds windowed mode that allows creation of an OpenGL context on an already existing window. Also, cleans up existing implementation of fullscreen mode. SetupGL still handles all aspects of GL setup on the Macintosh.
Version 1.0: Added PreflightGL () function. Fixed various minor errors. Corrected fade implementation. Added a little more robustness in the application end in failure conditions, fixed problem with aglFont handling.
SetupGL is a set of functions that can be used in new and existing applications to handle all aspects of OpenGL setup on the Macintosh under OS 9. It is designed to handle windowed or full screen set up with good error handling and fall back cases. The key to SetupGL is that it attempts to match your 3D context requests with the device that is able to handle them rather than pick a single device and hoping that it can handle the 3D requirements. A version of SetupGL is used in the "Quake III Arena" for the Macintosh by id Software.
To use it one fills out the structGLInfo structure (outlined in SetupGL.h) with the requirements and request for the context desired. Then a call to BuildGL will allocate the best matching context if able. BuildGL will set through all available graphics devices attempting to allocate the requested context. If it is unable an error will be reported thought the ReportError function. Currently, ReportError is set to send a debugstr on error, applications will likely need to override this with a more appropriate error reporting method.
SetupGL also has some unique features:
- The texture RAM variable in the structGLInfo allows you to specify an amount of texture memory, over and above the buffer requirements, that the device must have to satisfy your requirements. This allows you to pick a maximum resolution and bit depth and allow SetupGL to find the resolution and bit depth that can actually be used while maintaining the requested amount of VRAM. This is done by setting fDepthMust and fSizeMust to false on entry, which allows SetupGL to set down in resolutions and pixel depths to get a match.
- It allows specification of a screen device to try first by enumeration of the screens. -1 indicates the main screen. Other screens are enumerated in order returned by DMGetFirstScreenDevice and DMGetNextScreenDevice with 0 being the first screen returned. If allocations on the desired screen fails SetupGL will automatically check the other screens.
- SetupGL provides the function BuildGLFromWindow and DestroyGLFromWindow to handle cases where you want to setup OpenGL on a preexisting window. Ensure you call the DestroyGLFromWindow to destroy the context.
- PauseGL and ResumeGL are provided to allow the user control over the screen. Suppose you wish to draw a movie in the same window as OpenGL is using, just call PauseGL, play your movie and then ResumeGL when finished to start drawing your OpenGL scene again.
- PreflightGL checks for existence of OpenGL and if required DrawSprocket
Compile time options to be aware of:
Error Handler.c:
kVerboseErrors: are error strings reported
SetupDSp.c:
kUseFades: are fades between resolution switches used
kUseRAMCheck: is estimated device RAM usage done
SetupGL is provided as sample code and is under constant updates. The areas where work is being done are:
- better support for resolutions requiring the user to verify the switch in DSp
- better frequency support for multiple resolution step down. Need to store frequency information with resolutions to enable better step down logic.
- better testing and support of full screen only devices.
Any suggestions and/or bugs can be directed to the Apple bug reporter at:
Descriptions of the operation of the major functions and the structures can be found in the SetupGL.h header file.
Note: Some of the access paths will have to reset to point to the location of the OpenGL SDK on your local system and this is built using Universal Interfaces 3.3.1
We hope this helps people get up and running with OpenGL in a quick and painless manner.
----
The include test application shows the basic use of SetupGL by building a context and letting the user control the specifications on the fly, rebuilding the context when the request changes. This code also demonstrates the use of aglFonts, providing reusable font drawing routines.
Full screen applcation controls are:
Left/right arrows: smaller or larger resolution context
Up/down arrows: 32/16 bit pixel depth toggle
left/right bracket: change requested screen down or up one
-/=: change frequency request down or up by one step
[/]: change display number requested (wont go below 0)
